HAL MDF types migration

This section provides information about the HAL MDF types migration.

Note

  • In HAL1, a single driver handles both MDF and ADF peripherals.

  • In HAL2, the HAL MDF driver has been split into two separate drivers HAL MDF and HAL ADF. For more details, see : MDF specific concept.

  • In HAL1, there are some types applicable for:

    • Both MDF and ADF peripheral.

    • MDF peripheral only.

    • ADF peripheral only.

  • In the following migration document when the type is applicable for both MDF and ADF the migration describes how to move from HAL1 MDF to HAL2 MDF. The same applies for ADF, example:

  • In HAL1, MDF_DmaConfigTypeDef structure becomes:

    • hal_mdf_dma_config_t in HAL2 MDF driver.

    • hal_adf_dma_config_t in HAL2 ADF driver.

  • When the type is applicable only for MDF the migration provides the equivalent for MDF.

  • When the type is applicable only for ADF the migration provides the equivalent for ADF.

Types applicable for MDF and ADF

HAL MDF callback ID type definition

HAL1

HAL2 

In HAL1, callback ID structure is provided to
manage both MDF and ADF register callbacks:

typedef enum
{
#define HAL_MDF_ACQ_COMPLETE_CB_ID,
#define HAL_MDF_ACQ_HALFCOMPLETE_CB_ID,
#define HAL_MDF_ERROR_CB_ID,
#define HAL_MDF_MSPDEINIT_CB_ID,
#define HAL_MDF_MSPINIT_CB_ID,
#define HAL_MDF_OLD_CB_ID,
#define HAL_MDF_SAD_CB_ID,
#define HAL_MDF_SNDLVL_CB_ID
} HAL_MDF_CallbackIDTypeDef;

  • Removed from HAL2 : the callback registration is managed by dedicated functions for each MDF and ADF event. For more details, see : HAL MDF register callback function

  • HAL_MDF_MSPINIT_CB_ID and HAL_MDF_MSPDEINIT_CB_ID are removed because the functions HAL_MDF_MspInit() and HAL_MDF_MspDeInit() are removed. For more details, see : HAL MDF init configuration details.

  • Same applies for ADF.

Related concepts:

HAL MDF state type definition

Important

  • In HAL1, a single global state machine HAL_MDF_StateTypeDef manages the entire MDF peripheral states.

  • In HAL2, state management is split into multiple separate state machines:

    • A global peripheral state machine hal_mdf_state_t with global states.

    • A serial interface state machine hal_mdf_serial_interface_state_t represent the specific serial interface configuration state.

    • A short circuit detector state machine hal_mdf_scd_state_t represent the specific short circuit detector configuration state.

    • A digital filter state machine hal_mdf_digital_filter_state_t represent the specific digital filter configuration state.

    • An out of limit detector state machine hal_mdf_old_state_t represent the specific out of limit detector configuration state.

HAL1

HAL2 

typedef enum
{
#define HAL_MDF_STATE_RESET,
#define HAL_MDF_STATE_READY,
#define HAL_MDF_STATE_ACQUISITION,
#define HAL_MDF_STATE_ERROR,
} HAL_MDF_StateTypeDef;

typedef enum
{
  HAL_MDF_STATE_RESET,
  HAL_MDF_STATE_IDLE,
  HAL_MDF_STATE_INIT,
  HAL_MDF_STATE_ACTIVE
} hal_mdf_state_t;

typedef enum
{
  HAL_MDF_SITF_STATE_RESET,
  HAL_MDF_SITF_STATE_IDLE,
  HAL_MDF_SITF_STATE_ACTIVE
} hal_mdf_serial_interface_state_t;

typedef enum
{
  HAL_MDF_SCD_STATE_RESET,
  HAL_MDF_SCD_STATE_IDLE,
  HAL_MDF_SCD_STATE_ACTIVE
} hal_mdf_scd_state_t;

typedef enum
{
  HAL_MDF_DFLT_STATE_RESET,
  HAL_MDF_DFLT_STATE_IDLE,
  HAL_MDF_DFLT_STATE_ACTIVE
} hal_mdf_digital_filter_state_t;

typedef enum
{
  HAL_MDF_OLD_STATE_RESET,
  HAL_MDF_OLD_STATE_IDLE,
  HAL_MDF_OLD_STATE_ACTIVE
} hal_mdf_old_state_t;

Important

  • In HAL1, a single global state machine HAL_ADF_StateTypeDef manages the entire ADF peripheral states.

  • In HAL2, state management is split into multiple separate state machines:

    • A global peripheral state machine hal_adf_state_t with global states.

    • A serial interface state machine hal_adf_serial_interface_state_t represent the specific serial interface configuration state.

    • A sound activity detector state machine hal_adf_sad_state_t represent the specific sound activity detector configuration state.

    • A digital filter state machine hal_adf_digital_filter_state_t represent the specific digital filter configuration state.

HAL1

HAL2 

typedef enum
{
#define HAL_MDF_STATE_RESET,
#define HAL_MDF_STATE_READY,
#define HAL_MDF_STATE_ACQUISITION,
#define HAL_MDF_STATE_ERROR,
} HAL_MDF_StateTypeDef;

typedef enum
{
  HAL_ADF_STATE_RESET,
  HAL_ADF_STATE_INIT,
  HAL_ADF_STATE_IDLE,
  HAL_ADF_STATE_ACTIVE
} hal_adf_state_t;

typedef enum
{
  HAL_ADF_SITF_STATE_RESET,
  HAL_ADF_SITF_STATE_IDLE,
  HAL_ADF_SITF_STATE_ACTIVE
} hal_adf_serial_interface_state_t;

typedef enum
{
  HAL_ADF_DFLT_STATE_RESET,
  HAL_ADF_DFLT_STATE_IDLE,
  HAL_ADF_DFLT_STATE_ACTIVE
} hal_adf_digital_filter_state_t;

typedef enum
{
  HAL_ADF_SAD_STATE_RESET,
  HAL_ADF_SAD_STATE_IDLE,
  HAL_ADF_SAD_STATE_ACTIVE
} hal_adf_sad_state_t;

Related concept:

HAL MDF clock trigger type definition

HAL1

HAL2

In HAL1, MDF_ClockTriggerTypeDef structure is used with the initialization context ( HAL_MDF_Init) as follows:

  • When the Activation field is set to ENABLE, the trigger is enabled and the fields source and edge are used to configure the corresponding register fields.

  • When the Activation field is set to DISABLE, the trigger enabling and configuration are ignored.

typedef struct
{
  FunctionalState Activation;
  uint32_t        Source;
  uint32_t        Edge;
} MDF_ClockTriggerTypeDef;

In HAL2, this structure is no longer available. Instead, the following functions are provided:

  • HAL_MDF_SetConfigOutputClockTrigger: configures the output clock trigger source and edge.

  • HAL_MDF_EnableOutputClockTrigger and HAL_MDF_DisableOutputClockTrigger: respectively enable and disable the output clock trigger.

HAL_MDF_SetConfigOutputClockTrigger(const hal_mdf_handle_t *hmdf,
                                    hal_mdf_output_clock_trigger_source_t source,
                                    hal_mdf_output_clock_trigger_edge_t edge);

HAL_MDF_EnableOutputClockTrigger(const hal_mdf_handle_t *hmdf);
HAL_MDF_DisableOutputClockTrigger(const hal_mdf_handle_t *hmdf);

HAL MDF common parameter type definition

HAL1

HAL2

In HAL1, clock trigger structure is provided for both MDF and ADF peripherals: 

typedef struct
{

  uint32_t                 InterleavedFilters;



  uint32_t                 ProcClockDivider;




  MDF_OutputClockTypeDef   OutputClock;




} MDF_CommonParamTypeDef;

In HAL2, this structure is no longer available. Instead, the following configuration functions are provided to set the different parameters: 



interleaved Filter not supported by ADF :
HAL_MDF_SetInterleavedFilters(const hal_mdf_handle_t *hmdf,
                              uint32_t interleaved_filters)


HAL_MDF_SetConfig(hal_mdf_handle_t *hmdf,
                  uint32_t proc_clock_divider)



HAL_MDF_SetConfigOutputClock(const hal_mdf_handle_t *hmdf,
                             hal_mdf_output_clock_pins_t pins,
                             uint32_t output_clock_divider)

HAL MDF DMA configuration type definition

HAL1

HAL2

In HAL1, DMA configuration structure is provided for both MDF and ADF peripherals: 

typedef struct
{
  uint32_t         Address;
  uint32_t         DataLength;
  FunctionalState  MsbOnly;
} MDF_DmaConfigTypeDef;



typedef struct
{
  uint32_t                      address;
  uint32_t                      data_length_byte;
  hal_mdf_dma_data_resolution_t data_resolution;
} hal_mdf_dma_config_t;

For ADF the corresponding structure is hal_adf_dma_config_t.

HAL MDF filter configuration type definition

HAL1

HAL2

In HAL1, MDF_FilterConfigTypeDef structure is provided to manage filter configuration and used within the function HAL_MDF_AcqStart: 



typedef struct
{
  uint32_t                  DataSource;
  uint32_t                  CicMode;
  uint32_t                  DecimationRatio;
  int32_t                   Gain;
  uint32_t                  AcquisitionMode;
  MDF_FilterTriggerTypeDef  Trigger;






  uint32_t                  Delay;


  int32_t                   Offset;

  MDF_ReshapeFilterTypeDef  ReshapeFilter;

  MDF_HighPassFilterTypeDef HighPassFilter;

  uint32_t                  FifoThreshold;

  uint32_t                  DiscardSamples;


  uint32_t                  SnapshotFormat;

  MDF_SoundActivityTypeDef  SoundActivity;

} MDF_FilterConfigTypeDef;

In HAL2, the equivalent structure hal_mdf_digital_filter_config_t is used by the function HAL_MDF_DFLT_SetConfig before starting the acquisition using the function HAL_MDF_DFLT_StartAcq that no longer take a configuration (which is done separately using setconfig function): 

typedef struct
{
  hal_mdf_dflt_data_source_t      data_source;
  hal_mdf_dflt_cic_mode_t         cic_mode;
  uint32_t                        decimation_ratio;
  int32_t                         gain;
  hal_mdf_dflt_acquisition_mode_t acquisition_mode;
  hal_mdf_dflt_trigger_config_t   trigger;
} hal_mdf_digital_filter_config_t;

Additionally, for the optional fields the following unitary configuration functions are provided: 

HAL_MDF_DFLT_SetSamplesDelay API

not supported by ADF:
HAL_MDF_DFLT_SetOffsetCompensation API

HAL_MDF_DFLT_EnableReshapeFilter API

HAL_MDF_DFLT_EnableHighPassFilter API

HAL_MDF_DFLT_SetFifoThreshold API

HAL_MDF_DFLT_SetDiscardSamples API

not supported by ADF:
HAL_MDF_DFLT_SetSnapshotFormat API

see : HAL MDF sound activity type definition

HAL MDF filter trigger type definition

HAL1

HAL2

In HAL1, filter trigger structure is provided for both MDF and ADF peripherals: 


typedef struct
{
  uint32_t  Source;
  uint32_t  Edge;
} MDF_FilterTriggerTypeDef;




typedef struct
{
  hal_mdf_dflt_trigger_source_t source;
  hal_mdf_dflt_trigger_edge_t   edge;
} hal_mdf_dflt_trigger_config_t;

For ADF the corresponding structure is hal_adf_dflt_trigger_config_t.

Related concept: Replaced TypeDef suffix with _t in type names

HAL MDF high pass filter type definition

HAL1

HAL2

In HAL1, high pass filter structure is provided for both MDF and ADF peripherals: 

typedef struct
{
  FunctionalState  Activation;


  uint32_t         CutOffFrequency;


} MDF_HighPassFilterTypeDef;

This structure is no longer provided. Instead, two functions are provided to respectively enable and disable the high pass filter with the cut off frequency provided as parameter to the enable function. Note that the default value after a hardware reset is high pass filter enabled. User can choose to call the disable function to disabled or keep it enabled if it is the required configuration: 

HAL_MDF_DFLT_EnableHighPassFilter(const hal_mdf_handle_t *hmdf,
                                    hal_mdf_block_index_t digital_filter_index,
                                    hal_mdf_dflt_hpf_cut_off_frequency_t cut_off_frequency)
HAL_MDF_DFLT_DisableHighPassFilter(const hal_mdf_handle_t *hmdf,
                                     hal_mdf_block_index_t digital_filter_index)

HAL MDF initialization type definition

HAL1

HAL2

In HAL1, MDF_InitTypeDef structure is used to configure the serial interface, the BSMX matrix and common parameters for acquisition such as the output clock, the processing clock divider and the interleaved filters: 

typedef struct
{
  MDF_SerialInterfaceTypeDef  SerialInterface;

  uint32_t                    FilterBistream;

  MDF_CommonParamTypeDef      CommonParam;
} MDF_InitTypeDef;

In HAL2, the configuration is split into different functions per block:






refer to : HAL MDF serial interface type definition 

use instead : for MDF : HAL_MDF_BSMX_SetConfig API
             for ADF : HAL_ADF_BSMX_SetConfig API

refer to : HAL MDF common parameter type definition

Note

HAL MDF output clock type definition

HAL1

HAL2

In HAL1, MDF_OutputClockTypeDef structure is provided for both MDF and ADF peripherals: 

typedef struct
{
  FunctionalState         Activation;



  uint32_t                Pins;
  uint32_t                Divider;


  MDF_ClockTriggerTypeDef Trigger;

} MDF_OutputClockTypeDef;

In HAL2, this structure is no longer available. Instead, the following unitary APIs are provided enable, disable and set the output clock parameters: 


HAL_MDF_EnableOutputClock(const hal_mdf_handle_t *hmdf,
                          hal_mdf_output_clock_pins_t pins)
HAL_MDF_DisableOutputClock(const hal_mdf_handle_t *hmdf,
                           hal_mdf_output_clock_pins_t pins)

HAL_MDF_SetConfigOutputClock(const hal_mdf_handle_t *hmdf,
                             hal_mdf_output_clock_pins_t pins,
                             uint32_t output_clock_divider)

HAL_MDF_SetConfigOutputClockTrigger(const hal_mdf_handle_t *hmdf,
                                    hal_mdf_output_clock_trigger_source_t source,
                                    hal_mdf_output_clock_trigger_edge_t edge)

HAL MDF reshape filter type definition

HAL1

HAL2

In HAL1, reshape filter structure is provided for both MDF and ADF peripherals: 

typedef struct
{

  FunctionalState  Activation;
  uint32_t         DecimationRatio;


} MDF_ReshapeFilterTypeDef;

In HAL2, this structure is no longer available. Instead, the following functions are provided to enable and disable the reshape filter with the decimation ratio being a parameter of the enable function: 



HAL_MDF_DFLT_EnableReshapeFilter(const hal_mdf_handle_t *hmdf,
                                 hal_mdf_block_index_t digital_filter_index,
                                 hal_mdf_dflt_rsf_decimation_ratio_t decimation_ratio)
HAL_MDF_DFLT_DisableReshapeFilter(const hal_mdf_handle_t *hmdf,
                                  hal_mdf_block_index_t digital_filter_index)

HAL MDF serial interface type definition

HAL1

HAL2

In HAL1, MDF_SerialInterfaceTypeDef structure is provided to configure and enable the serial interface for both MDF and ADF peripherals: 

typedef struct
{
  uint32_t         Mode;
  uint32_t         ClockSource;
  uint32_t         Threshold;









  FunctionalState  Activation;


} MDF_SerialInterfaceTypeDef;

In HAL2, the following structure and functions are provided:



to configure the serial interface use: 

typedef struct
{
  hal_mdf_serial_interface_mode_t         mode;
  hal_mdf_serial_interface_clock_source_t clock_source;
  uint32_t                                threshold;
} hal_mdf_serial_interface_config_t;

HAL_MDF_SITF_SetConfig(hal_mdf_handle_t *hmdf,
                       hal_mdf_block_index_t serial_interface_index,
                       const hal_mdf_serial_interface_config_t *p_config)

to start and stop (enable/disable) the serial interface use: 

HAL_MDF_SITF_Start(hal_mdf_handle_t *hmdf,
                   hal_mdf_block_index_t serial_interface_index)
HAL_MDF_SITF_Stop(hal_mdf_handle_t *hmdf,
                  hal_mdf_block_index_t serial_interface_index)

Related concept:

HAL MDF handle type definition

HAL1

HAL2

In HAL1, one driver manages both MDF and ADF peripherals. So a single handle structure MDF_HandleTypeDef is provided to manage both peripherals. 

MDF_HandleTypeDef

In HAl2, each peripheral has its own dedicated driver: 


For MDF driver : hal_mdf_handle_t

For ADF the corresponding handle structure is hal_adf_handle_t.

Related concepts:

Types applicable for MDF only

HAL MDF integrator type definition

HAL1

HAL2

In HAL1, the structure MDF_IntegratorTypeDef is provided to configure the DFLT integrator as follows:

  • When the Activation field is set to ENABLE, the integrator fields Value and OutputDivision are used to configure the corresponding MDF_DFLTxINTR register.

  • When the Activation field is set to DISABLE, the integrator Value and OutputDivision are ignored, and instead the corresponding MDF_DFLTxINTR register is set to 0, which bypasses the integrator.

typedef struct
{
  FunctionalState  Activation;
  uint32_t         Value;
  uint32_t         OutputDivision;
} MDF_IntegratorTypeDef;

In HAL2, the following function is provided to configure the DFLT integrator: 




hal_status_t HAL_MDF_DFLT_SetIntegrator(const hal_mdf_handle_t *hmdf,
                                         hal_mdf_block_index_t digital_filter_index,
                                         uint32_t value,
                                         hal_mdf_dflt_int_output_division_t output_division);

The user can individually specify the desired integrator value and output_division.

To reproduce the HAL1 DISABLE behavior in HAL2, the user must set both value and output_division to 0, which configures the integrator in bypass mode.

HAL MDF out of limit configuration type definition

HAL1

HAL2

In HAL1, out of limit configuration structure is provided for MDF peripheral only (not supported by ADF): 

typedef struct
{
  uint32_t  OldCicMode;
  uint32_t  OldDecimatio;
  int32_t   HighThresh;
  int32_t   LowThresh;
  uint32_t  OldEve;
  uint32_t  BreakSignal;
} MDF_OldConfigTypeDef;




typedef struct
{
  hal_mdf_old_cic_order_t    cic_order;
  uint32_t                   decimation_ratio;
  int32_t                    high_threshold;
  int32_t                    low_threshold;
  hal_mdf_old_event_config_t event_config;
  uint32_t                   break_signals;
} hal_mdf_old_config_t;

Related concept:

HAL MDF short circuit detector configuration type definition

HAL1

HAL2

In HAL1, short circuit detector structure is provided for MDF peripheral (not supported by ADF): 

typedef struct
{
  uint32_t  Threshold;
  uint32_t  BreakSignal;
} MDF_ScdConfigTypeDef;

In HAL2, this structure is no longer available. Instead, a short circuit detector configuration function is provided with the threshold and break signal being parameters to the function: 


HAL_MDF_SCD_SetConfig(hal_mdf_handle_t *hmdf,
                      hal_mdf_block_index_t short_circuit_detector_index,
                      uint32_t threshold,
                      uint32_t break_signals)

HAL MDF snapshot parameter type definition

HAL1

HAL2

In HAL1, snapshot parameter structure is provided for MDF peripheral only (not supported by ADF): 

typedef struct
{
  int32_t   Value;
  uint32_t  DecimationCounter;
  uint32_t  IntegratorCounter;
} MDF_SnapshotParamTypeDef;



typedef struct
{
  int32_t   value;
  uint32_t  decimation_counter;
  uint32_t  integrator_counter;
} hal_mdf_dflt_snapshot_param_t;

Related concept:

Types applicable for ADF only

HAL MDF sound activity type definition

HAL1

HAL2

In HAL1, the following structure is provided to configure and enable the ADF sound activity detector (not supported by MDF): 

typedef struct
{
  uint32_t         Mode;
  uint32_t         DataMemoryTransfer;
  uint32_t         SoundTriggerEvent;
  uint32_t         MinNoiseLevel;









  FunctionalState  Activation;





  uint32_t         FrameSize;


  uint32_t         HangoverWindow;


  uint32_t         LearningFrames;



  FunctionalState  Hysteresis;


  uint32_t         AmbientNoiseSlope;


  uint32_t         SignalNoiseThreshold;



  FunctionalState  SoundLevelInterrupt;

} MDF_SoundActivityTypeDef;

In HAL2, this structure is no longer available. Instead, the following APIs are provided to configure and start/stop (enable/disable) the ADF sound activity detector:

To configure the SAD use: 

typedef struct
{
  hal_adf_sad_mode_t            mode;
  hal_adf_sad_memory_transfer_t memory_transfer;
  hal_adf_sad_trigger_event_t   trigger_event;
  uint32_t                      minimum_ambient_noise;
} hal_adf_sad_config_t;

HAL_ADF_SAD_SetConfig(hal_adf_handle_t *hadf,
                      hal_adf_block_index_t sound_activity_detector_index,
                      const hal_adf_sad_config_t *p_config)

To start/stop the SAD use: 

HAL_ADF_SAD_Start(hal_adf_handle_t *hadf,
                  hal_adf_block_index_t sound_activity_detector_index)
HAL_ADF_SAD_Stop(hal_adf_handle_t *hadf,
                 hal_adf_block_index_t sound_activity_detector_index)

Additional unitary functions are provided to set the remaining optional parameters: 

HAL_ADF_SAD_SetFrameSize(const hal_adf_handle_t *hadf,
                         hal_adf_block_index_t sound_activity_detector_index,
                         hal_adf_sad_frame_size_t frame_size)
HAL_ADF_SAD_SetHangoverTimeWindow(const hal_adf_handle_t *hadf,
                                  hal_adf_block_index_t sound_activity_detector_index,
                                  hal_adf_sad_hangover_time_window_t hangover_time_window)
HAL_ADF_SAD_SetLearningFrames(const hal_adf_handle_t *hadf,
                              hal_adf_block_index_t sound_activity_detector_index,
                              hal_adf_sad_learning_frames_t learning_frames)
HAL_ADF_SAD_EnableHysteresis(const hal_adf_handle_t *hadf,
                             hal_adf_block_index_t sound_activity_detector_index)
HAL_ADF_SAD_DisableHysteresis(const hal_adf_handle_t *hadf,
                              hal_adf_block_index_t sound_activity_detector_index)
HAL_ADF_SAD_SetAmbientNoiseSlope(const hal_adf_handle_t *hadf,
                                     hal_adf_block_index_t sound_activity_detector_index,
                                     uint32_t ambient_noise_slope)
HAL_ADF_SAD_SetSignalToNoiseThreshold(const hal_adf_handle_t *hadf,
                                      hal_adf_block_index_t sound_activity_detector_index,
                                      hal_adf_sad_signal_to_noise_threshold_t threshold)
HAL_ADF_SAD_Start_IT(hal_adf_handle_t *hadf,
                         hal_adf_block_index_t sound_activity_detector_index)
HAL_ADF_SAD_Stop_IT(hal_adf_handle_t *hadf,
                        hal_adf_block_index_t sound_activity_detector_index)